Web services provide access to various types of data such as maps, email, news, and social networking information. Web service providers often provide application programming interfaces (APIs) so that software developers can have controlled access to web services and data. An API is a code-based specification which allows software components to communicate with one another. APIs may contain information such as the methods available and the data returned by the available methods from a particular web service.
For example, a web service provider may create a web mapping service and provide a Map API for software developers to access the mapping service's functionality. The Map API may contain information about the web mapping service including methods to obtain: directions to a place, the travel distance between places, the travel time between places, and a place's elevation. If a software developer is building an application for a fast food restaurant, the developer may want to use the Map API to allow a user to request directions to the restaurant from the user's current location. The developer does not have to write the map-specific code to obtain directions, but can instead use the Map API to access the web service provider's functionality and obtain the directions. The developer can write code that calls the methods that are defined by the API and uses the data that is returned from the methods.
Most API providers also give developers a client library and/or documentation which demonstrates how to retrieve data objects from their respective APIs. An API client library may include a discovery document as generated code which shows a developer how to access objects and methods. The discovery document is structured data that may contain: (1) a list of API resource schemas that describe the data developers have access to in each API, (2) a list of API methods and available parameters for each method, and (3) the format of the information that will be returned from each method when the method is accessed.
Data typically needs to be serialized by a web service before it is sent to a remote client. Serialization is the process of converting classes and objects into a linear sequence of bytes for either storage or transmission to another location. Often the linear sequence of bytes is represented as a string. Data also needs to be deserialized into classes and objects when the data is received via an API by the remote client. Deserialization is the process of taking in the linear sequence of bytes and recreating classes and objects from these bytes. Most data conversion software for serialization and deserialization is written by hand and parses data into manually-created classes and objects. While this approach may be viable for a small number of APIs, mistakes are likely when data must be parsed for numerous APIs or when APIs are frequently updated.